How to Structure Content for GitHub Copilot Agent Files

tech
github-copilot
prompt-engineering
agents
Create specialized AI personas with custom agent files - learn agent structure, tool configuration, handoffs, and composable AI workflows
Author

Dario Airoldi

Published

December 26, 2025

How to Structure Content for GitHub Copilot Agent Files

Custom agents enable you to create specialized AI personas tailored to specific development roles and tasks.
Agent files (.agent.md) define the behavior, available tools, and instructions for these personas, creating reusable configurations that can be quickly activated in chat.
This article explores how to structure agent files effectively and explains how they interact with prompts and instructions to create powerful, composable AI workflows.

Table of Contents

🤖 Understanding Custom Agents

Custom agents are AI personas that you can switch between in GitHub Copilot Chat. Each agent has:

  • A specific role or expertise (e.g., security reviewer, planner, implementer)
  • Restricted tool access tailored to its function
  • Specialized instructions for how it should operate
  • Optional handoff capabilities to transition between agents

Unlike prompt files that are invoked on-demand for specific tasks, agents provide ongoing contextual behavior.
When you switch to a custom agent, all subsequent chat interactions adopt that agent’s persona, tools, and guidelines until you switch to a different agent.

Why Use Custom Agents?

Task-appropriate capabilities: Different tasks require different tools. A planning agent might only need read-only tools for research and analysis to prevent accidental code changes, while an implementation agent would need full editing capabilities.

Specialized behavior: Custom agents provide specialized instructions that define how the AI should operate. For instance, a planning agent could instruct the AI to collect project context and generate a detailed implementation plan, while a code review agent might focus on identifying security vulnerabilities and suggesting improvements.

Workflow orchestration: Through handoffs, agents can create guided sequential workflows that transition between specialized personas with suggested next steps, giving developers control to review and approve each stage.

Availability

  • VS Code: Custom agents are available from version 1.106+
  • Visual Studio: Not currently supported (but see AGENTS.md for Copilot Coding Agent instructions)
  • Storage Locations:
    • Workspace: .github/agents/*.agent.md (shared with team via Git)
    • User profile: Personal agents available across all workspaces

Execution Contexts (v1.107+)

VS Code 1.107 introduced Agent HQ, a unified interface for managing agent sessions across three execution contexts:

Context Description Isolation Best For
Local Interactive agent in current workspace None—modifies workspace directly Quick tasks, interactive refinement
Background Runs autonomously using Git work trees Full—uses isolated work tree Long-running tasks without blocking workflow
Cloud Runs on GitHub infrastructure, creates PRs Full—new branch and PR Large changes, async collaboration

Claude Skills support is also available in v1.107+, extending agent capabilities through the Claude skills ecosystem.

For comprehensive coverage of Agent HQ, session management, and work tree isolation workflows, see 📎 Appendix: Unified Agent Architecture.

🔄 How Agents Differ from Prompts and Instructions

Understanding the distinction between these three file types is crucial for effective organization:

Comparison Table

Aspect Prompt Files (.prompt.md) Agent Files (.agent.md) Instruction Files (.instructions.md)
Purpose Define specific tasks/workflows Define AI personas with persistent behavior Define context-specific rules
Activation On-demand via /promptName Switched to via agent picker Automatic when conditions match
Scope Single execution Ongoing chat session context All operations matching applyTo pattern
Reusability Task-specific, one prompt = one job Role-specific, one agent = multiple tasks Context-specific, always active when relevant
Tool Control Can specify tools for this prompt Defines default tools for this persona No tool control (relies on agent/prompt)
Can Reference Agents (via agent field), tools, instructions Tools, instructions (via Markdown links) Tools (via #tool: syntax)
Best For “Generate React form”, “Review API security” “Planner persona”, “Security reviewer role” “Python coding standards”, “C# conventions”

Conceptual Model

Think of these file types as layers in a composable system:

┌─────────────────────────────────────────────────────────┐
│ PROMPT FILE                                             │
│ "Generate React form component"                         │
│ • References agent: planner                             │
│ • Adds task-specific tools: ['fetch']                   │
│ • Invokes with: /create-react-form                      │
└────────────────┬────────────────────────────────────────┘
                 │
                 │ Uses agent configuration
                 ▼
┌─────────────────────────────────────────────────────────┐
│ AGENT FILE                                              │
│ "Planner" persona                                       │
│ • Default tools: ['search', 'codebase', 'usages']       │
│ • Behavior: Generate plans, no code edits              │
│ • Can handoff to: implementation agent                  │
└────────────────┬────────────────────────────────────────┘
                 │
                 │ Reads relevant instructions
                 ▼
┌─────────────────────────────────────────────────────────┐
│ INSTRUCTION FILES                                       │
│ • "react-guidelines.instructions.md" (applyTo: **/*.tsx)│
│ • "api-standards.instructions.md" (applyTo: **/api/**) │
│ • "security-rules.instructions.md" (applyTo: **)       │
└─────────────────────────────────────────────────────────┘

Information Flow

When you invoke a prompt that references an agent:

  1. Prompt provides task-specific instructions and may override tools
  2. Agent provides persona, default tools, and behavioral guidelines
  3. Instructions are automatically included based on file context (applyTo patterns)
  4. Tool Priority: Prompt tools > Agent tools > Default agent tools

📋 Agent File Structure

Agent files use the .agent.md extension and follow this structure:

---
description: Brief description shown in agent picker
name: Agent name (defaults to filename if omitted)
argument-hint: Placeholder text in chat input (optional)
tools: ['tool1', 'tool2', 'toolset-name']
model: Preferred model (e.g., Claude Sonnet 4, GPT-4o)
target: vscode | github-copilot
handoffs:
  - label: Button text for handoff
    agent: target-agent-name
    prompt: Message to send to target agent
    send: false  # auto-submit if true
---

# Agent Instructions

Your agent's system instructions in Markdown format.

Define:
- The agent's role and expertise
- How it should approach tasks
- What output format to produce
- Any constraints or guidelines

You can reference other files using Markdown links.
Reference tools using #tool:<tool-name> syntax.

YAML Frontmatter Fields

Core Fields

Field Type Required Description
description String No Brief description shown as placeholder text in chat input
name String No Agent name (defaults to filename without extension)
argument-hint String No Hint text shown in chat input field
tools Array No List of tools/tool sets available to this agent
model String No Preferred AI model (e.g., “Claude Sonnet 4”, “GPT-4o”). BYOK models supported in v1.107+
target String No vscode (local execution) or github-copilot (cloud/remote execution). Affects available tools and execution context. See Execution Contexts

Advanced Fields

Field Type Description
mcp-servers Array MCP server configurations (for github-copilot target only)
handoffs Array Workflow transitions to other agents
handoffs.label String Button text displayed for handoff
handoffs.agent String Target agent identifier
handoffs.prompt String Message to send when handing off
handoffs.send Boolean Auto-submit prompt (default: false)

Body Content

The agent file body contains the agent’s instructions in Markdown format. This is where you:

  • Define the persona: “You are a senior security engineer…”
  • Specify behavior: “Always prioritize security over convenience…”
  • Describe output format: “Generate a report with the following sections…”
  • Set constraints: “Never modify files directly; propose changes only…”

You can reference:

  • Other files via Markdown links: [Review Guidelines](../instructions/review-process.md)
  • Tools via syntax: Use #tool:codebase to search for similar patterns

🎯 Designing Agent Personas

Effective agent design starts with clear persona definition. Here’s a framework for creating specialized agents:

The Five Elements of Agent Persona

1. Role Definition

Clearly state the agent’s expertise and responsibility:

You are a **security-focused code reviewer** specializing in identifying vulnerabilities in web applications.

2. Behavioral Guidelines

Define how the agent approaches tasks:

Your approach:
- Prioritize identifying security vulnerabilities (XSS, SQL injection, authentication bypass)
- Consider both immediate threats and long-term security architecture
- Provide actionable remediation steps with code examples
- Flag compliance issues (OWASP Top 10, CWE)

3. Output Format

Specify the structure of responses:

Format your review as:

## Summary
Brief overview of findings (2-3 sentences)

## Critical Issues
- [Issue]: Description and impact
- **Remediation**: Step-by-step fix

## Recommendations
- Best practices to prevent similar issues

4. Constraints

Set boundaries on what the agent should or shouldn’t do:

Constraints:
- Do NOT modify code directly; propose changes for review
- Do NOT skip security checks for "convenience"
- ALWAYS verify authentication and authorization logic
- Ask for clarification if security context is ambiguous

5. Tool Usage

Explain how the agent should leverage available tools:

Available tools:
- Use #tool:codebase to find similar security patterns
- Use #tool:fetch to check CVE databases for known vulnerabilities
- Use #tool:search to locate related test files

Example: Complete Agent Persona

Here’s a full example of a well-structured planning agent:

---
description: Generate implementation plans for features and refactoring
name: Planner
tools: ['fetch', 'githubRepo', 'search', 'usages', 'codebase']
model: Claude Sonnet 4
handoffs:
  - label: Start Implementation
    agent: agent
    prompt: Implement the plan outlined above.
    send: false
---

# Planning Agent

You are a **senior solution architect** tasked with creating detailed, actionable implementation plans.

## Your Role

Generate comprehensive plans that guide developers through complex features or refactoring tasks. Focus on clarity, completeness, and feasibility.

## Approach

1. **Understand Context**
   - Use #tool:codebase to explore existing architecture
   - Use #tool:search to find related components
   - Use #tool:fetch to research best practices and patterns

2. **Analyze Requirements**
   - Identify functional and non-functional requirements
   - Flag potential risks or challenges
   - Note dependencies on other systems/components

3. **Design Solution**
   - Break down work into logical, testable phases
   - Identify reusable patterns and components
   - Consider error handling, logging, and monitoring

4. **Document Plan**
   - Create clear, numbered implementation steps
   - Specify files to create/modify for each step
   - Include test strategy for each component

## Output Format

Overview

[Brief description of the feature/refactoring and its purpose]

Requirements

  • Functional: [What the system must do]
  • Non-Functional: [Performance, security, scalability considerations]
  • Dependencies: [External systems, libraries, or prerequisites]

Architecture Changes

[High-level architectural modifications, if any]

Implementation Steps

Phase 1: [Phase Name]

  1. Step: [Detailed description]
    • Files: [Files to create/modify]
    • Changes: [What changes to make]
    • Tests: [What to test]

Phase 2: [Next Phase]

…

Testing Strategy

  • Unit tests: [What to cover]
  • Integration tests: [What scenarios]
  • Manual verification: [What to check]

Risks and Mitigations

  • Risk: [Potential issue]
    • Mitigation: [How to address it] ```

Constraints

  • Do NOT write implementation code; describe what should be implemented
  • Do NOT skip important steps for brevity; completeness is critical
  • ALWAYS consider backward compatibility and migration paths
  • Ask clarifying questions if requirements are ambiguous

Handoff

When the plan is complete and approved, use the “Start Implementation” handoff to transition to the implementation agent with full context.


# 🔗 Agent Interactions and Handoffs

<mark>**Handoffs**</mark> are one of the most powerful features of custom agents. They enable orchestrated, multi-step workflows where control transitions between specialized agents.

## How Handoffs Work

When an agent completes its task, handoff buttons appear in the chat interface. Clicking a handoff button:

1. Switches to the target agent
2. Pre-fills the chat input with the specified prompt
3. Optionally auto-submits the prompt (if `send: true`)
4. Carries forward the conversation context

### Handoff Configuration

```yaml
handoffs:
  - label: Start Implementation        # Button text
    agent: agent                       # Target agent (built-in or custom)
    prompt: Implement the plan above.  # Message to send
    send: false                        # Manual submission (user reviews first)

Common Handoff Patterns

1. Plan → Implement

Planning agent generates a detailed plan, then hands off to implementation agent:

# planner.agent.md
handoffs:
  - label: Start Implementation
    agent: agent
    prompt: Implement the plan outlined above, starting with Phase 1.
    send: false

Workflow:

  1. User asks for implementation plan
  2. Planner agent generates detailed steps
  3. User reviews plan
  4. User clicks “Start Implementation”
  5. Implementation agent begins coding

2. Implement → Review

Implementation agent writes code, then hands off to review agent:

# implementer.agent.md
handoffs:
  - label: Review Changes
    agent: security-reviewer
    prompt: Review the changes made in this session for security vulnerabilities.
    send: true  # Auto-submit since context is clear

3. Write Failing Tests → Implement

Test-first approach: generate failing tests, review them, then implement to make them pass:

# test-writer.agent.md
handoffs:
  - label: Implement to Pass Tests
    agent: agent
    prompt: Implement the code changes needed to make these tests pass.
    send: false

4. Multi-Stage Refinement

Create a chain of specialized agents:

Research → Plan → Implement → Review → Document

Each agent hands off to the next, building on previous context.

Handoff Best Practices

Practice Rationale
Use send: false for critical transitions Gives user chance to review before proceeding
Use send: true for routine transitions Streamlines workflow when next step is obvious
Include context in prompt “Implement the plan above” references specific context
Name handoffs clearly “Start Implementation” is clearer than “Next Step”
Chain related agents Reviewer → Documenter → Deployer creates logical flow

⚙️ Tool Configuration for Agents

Tools define what actions an agent can perform. Proper tool selection ensures agents have the right capabilities without unnecessary access.

Understanding Tool Priority

When multiple sources define tools, this priority order applies:

  1. Prompt file tools field (highest priority)
  2. Referenced agent’s tools field
  3. Default tools for current agent mode

Example:

# Agent defines default tools
# security-reviewer.agent.md
tools: ['codebase', 'search', 'fetch']

# Prompt can override/extend
# api-security-audit.prompt.md
agent: security-reviewer
tools: ['codebase', 'search', 'fetch', 'githubRepo']  # Adds githubRepo

Tool Categories

Built-in Tools

Tool Purpose Read-Only
codebase Semantic code search ✓
editor File read/write operations ✗
filesystem Directory navigation, file queries ✓
fetch Retrieve web content ✓
web_search Internet search ✓
search Workspace text search ✓
usages Find code usages/references ✓
problems Get errors/warnings ✓
changes View git changes ✓

Tool Sets

Predefined groups of related tools:

Tool Set Included Tools Use Case
#edit editor, filesystem Code modification
#search codebase, search, usages Code discovery
#reader codebase, problems, changes, usages Context gathering

MCP Tools

Tools from Model Context Protocol servers (e.g., @github, @azure):

tools: ['codebase', '@github/*']  # Include all tools from GitHub MCP server

Tool Selection Strategy

Planning Agent (Read-Only Focus)

tools: ['fetch', 'githubRepo', 'search', 'usages', 'codebase']

Rationale: Needs to gather information but shouldn’t modify code accidentally.

Implementation Agent (Full Access)

tools: ['editor', 'filesystem', 'codebase', 'search']

Rationale: Needs file editing capabilities plus context awareness.

Review Agent (Read + External Research)

tools: ['codebase', 'search', 'fetch', 'web_search']

Rationale: Reads code, searches for patterns, fetches security databases/documentation.

Testing Agent (Read + Execute)

tools: ['codebase', 'editor', 'terminal']

Rationale: Creates test files and runs tests via terminal.

Restricting Tools for Safety

Limit tools to prevent unintended actions:

# Security reviewer should NOT edit files
tools: ['codebase', 'search', 'fetch']  # Excludes 'editor'

# Planner should NOT execute commands
tools: ['codebase', 'search', 'usages']  # Excludes 'terminal'

🧩 Composing Agents with Prompts and Instructions

The true power of agents emerges when combined with prompts and instructions. Here’s how to compose them effectively:

Pattern 1: Prompt References Agent

A prompt can reference a custom agent to inherit its tools and behavior:

# api-security-audit.prompt.md
---
name: api-security-audit
description: Perform comprehensive security audit of REST API
agent: security-reviewer  # Use security-reviewer agent
tools: ['codebase', 'fetch', 'githubRepo']  # Override with specific tools
---

Perform a security audit of the API in ${selection}.

Focus on:
- Authentication and authorization
- Input validation
- SQL injection vulnerabilities
- XSS risks

Use #tool:fetch to check OWASP guidelines.
Use #tool:githubRepo to find similar secure implementations.

Result: Prompt gets security-reviewer’s behavior + overridden tools.

Pattern 2: Agent References Instructions

An agent can reference instruction files for reusable guidelines:

---
name: security-reviewer
tools: ['codebase', 'search', 'fetch']
---

# Security Reviewer Agent

You are a security expert. Follow the guidelines in:
- [Security Best Practices](../instructions/security-standards.instructions.md)
- [OWASP Compliance Checklist](../instructions/owasp-checklist.instructions.md)

Your task is to identify vulnerabilities and propose fixes.

Result: Agent inherits detailed security rules from instruction files.

Pattern 3: Automatic Instruction Application

Instructions apply automatically based on applyTo patterns:

# python-security.instructions.md
---
applyTo: "**/*.py"
---

# Python Security Guidelines

- Always use parameterized queries, never string concatenation for SQL
- Validate all user input with type checking
- Use `secrets` module for tokens, never hardcode credentials

When security-reviewer agent analyzes a .py file, these instructions are automatically included.

Pattern 4: Workflow Composition

Combine agents, prompts, and instructions for complete workflows:

1. User invokes: /plan-feature
   → Uses planner agent
   → Includes project-architecture.instructions.md (auto-applied)
   → Generates implementation plan

2. User clicks handoff: "Start Implementation"
   → Switches to implementation agent
   → Includes language-specific instructions (auto-applied)
   → Begins coding

3. User clicks handoff: "Review Changes"
   → Switches to security-reviewer agent
   → Includes security-standards.instructions.md (auto-applied)
   → Reviews for vulnerabilities

Reusability Example

Scenario: Multiple prompts use the same agent with different focuses

# Agent: test-specialist.agent.md
---
tools: ['codebase', 'editor', 'search']
---
You are a testing expert. Generate comprehensive test suites.
# Prompt 1: unit-tests.prompt.md
agent: test-specialist
---
Generate unit tests for ${selection} with 100% coverage.
# Prompt 2: integration-tests.prompt.md
agent: test-specialist
---
Generate integration tests for the API workflow in ${file}.

Both prompts reuse test-specialist’s tools and behavior but define different tasks.

💡 Decision Framework: When to Use Each File Type

Use this decision tree to determine the right file type:

Should this be a Prompt, Agent, or Instruction?

Start Here: What are you defining?

┌─────────────────────────────────────────────────────────────┐
│ QUESTION: What am I trying to define?                        │
└───────────────────┬─────────────────────────────────────────┘
                    │
        ┌───────────┴───────────┐
        │                       │
    ┌───▼────┐             ┌────▼───┐
    │ Task   │             │ Rules  │
    │        │             │        │
    └───┬────┘             └────┬───┘
        │                       │
        │                       │
┌───────▼────────────┐   ┌──────▼─────────────────┐
│ Is it invoked      │   │ Does it apply to       │
│ on-demand for a    │   │ specific file types/   │
│ specific job?      │   │ contexts automatically?│
└───────┬────────────┘   └──────┬─────────────────┘
        │                       │
    YES │                   YES │
        │                       │
┌───────▼────────────┐   ┌──────▼─────────────────┐
│ Does it define     │   │                         │
│ persistent         │   │  → INSTRUCTION FILE     │
│ behavior for       │   │    (.instructions.md)   │
│ multiple tasks?    │   │                         │
└───────┬────────────┘   └─────────────────────────┘
        │
    YES │  NO
        │   │
        │   └─────────────┐
        │                 │
┌───────▼────────────┐   │
│  → AGENT FILE      │   │
│    (.agent.md)     │   │
└────────────────────┘   │
                         │
                  ┌──────▼─────────────┐
                  │  → PROMPT FILE     │
                  │    (.prompt.md)    │
                  └────────────────────┘

Detailed Decision Criteria

Use a Prompt File when:

✅ Defining a specific task that users invoke on-demand
✅ Task has a clear start and end point
✅ Users need to provide input/context when invoking
✅ Task is standalone (doesn’t require persistent persona)
✅ Different users will invoke it for different scenarios

Examples:

  • Generate React form component
  • Perform security audit of API
  • Create migration script
  • Write documentation for function

Use an Agent File when:

✅ Defining an AI persona/role (not a single task)
✅ Behavior should persist across multiple interactions
✅ Multiple prompts will use this persona
✅ You need to restrict tool access for this role
✅ You want to enable handoffs to/from this agent

Examples:

  • Security Reviewer (persona for any security task)
  • Planner (generates plans for various features)
  • Test Specialist (creates tests for different components)
  • Documentation Expert (writes any type of documentation)

Use an Instruction File when:

✅ Defining rules that apply automatically
✅ Rules are specific to file types, languages, or directories
✅ Guidelines should influence ALL work in that context
✅ Rules are orthogonal to task/persona (apply everywhere)
✅ You want both prompts and agents to follow these rules

Examples:

  • Python coding standards (applies to all .py files)
  • API design guidelines (applies to api/ directory)
  • Security requirements (applies everywhere: **)
  • React component conventions (applies to .tsx files)

Common Scenarios

Scenario Solution
“Generate unit tests for this function” Prompt file (generate-unit-tests.prompt.md)
“I need a testing expert persona” Agent file (test-specialist.agent.md)
“All Python code should use type hints” Instruction file (python-standards.instructions.md, applyTo: **/*.py)
“Create a workflow: plan → implement → review” Three agents with handoffs (planner.agent.md → implementer.agent.md → reviewer.agent.md)
“Security audit for APIs” Prompt references security agent (api-audit.prompt.md with agent: security-reviewer)
“C# naming conventions” Instruction file (csharp-standards.instructions.md, applyTo: **/*.cs)

Anti-Patterns to Avoid

❌ Don’t create an agent for every single task

  • ✅ Do create agents for roles/personas, prompts for tasks

❌ Don’t duplicate rules across prompts

  • ✅ Do extract common rules into instruction files

❌ Don’t create instructions for task-specific workflows

  • ✅ Do use prompts for task workflows, instructions for universal rules

❌ Don’t create a prompt that just switches to an agent

  • ✅ Do let users switch agents directly; prompts should add task-specific context

❌ Don’t hardcode tool lists in every prompt

  • ✅ Do define default tools in agents, override in prompts only when needed

📏 Agent File Length Best Practices

Agent files are persistent configurations that remain loaded throughout chat sessions, making length optimization even more critical than for prompts. Well-sized agents improve performance and maintain clarity of purpose.

Token Budget for Agents

Agent files are loaded:

  • When switched to via agent picker
  • Referenced by prompts (via agent: field)
  • Applied to all subsequent chat turns until switched away

Recommended Sizes:

Agent Type Recommended Max Typical Size Reason
Specialist Agent 1,000 tokens (~750 words) 500-800 tokens Clear role, focused tools, concise guidelines
Planner Agent 1,500 tokens (~1,125 words) 800-1,200 tokens Needs output format templates, phase structures
Review Agent 1,200 tokens (~900 words) 700-1,000 tokens Checklists, validation criteria, reporting format
Complex Orchestrator 2,000 tokens (~1,500 words) 1,200-1,600 tokens Multi-phase workflows, multiple handoffs

Critical Threshold: Agents exceeding 2,000 tokens should be split or refactored.

Why Agent Length Matters More

Unlike prompts (invoked once per task), agents:

  • Persist across multiple chat turns
  • Accumulate with conversation history in the context window
  • Combine with applied instruction files
  • Compound when prompts reference them

Example Impact:

Agent (1,500 tokens)
+ 3 instruction files (300 tokens each = 900 tokens)
+ Conversation history (5 turns = 2,000 tokens)
+ Current prompt (800 tokens)
+ Referenced files (3,000 tokens)
= 8,200 tokens consumed before AI generates response

Optimal Agent Structure

Good: Focused and Concise (800 tokens)

---
description: "Security code reviewer with OWASP expertise"
tools: ['codebase', 'fetch']
handoffs:
  - agent: implementer
    description: "Apply security fixes"
---

# Security Reviewer

## Your Expertise
Senior security engineer specializing in OWASP Top 10 and secure coding practices.

## Approach
1. Scan code for common vulnerabilities
2. Reference OWASP guidelines
3. Provide specific fix recommendations

## 🚨 CRITICAL BOUNDARIES

### ✅ Always Do
- Check for input validation gaps
- Flag hardcoded secrets
- Verify authentication/authorization
- Use #tool:codebase to find similar patterns

### 🚫 Never Do
- Never modify code (read-only mode)
- Never approve without thorough review
- Never skip SQL injection checks

## Output Format
## Security Review: ${fileName}

### Vulnerabilities Found
[Categorized by severity]

### Recommendations
[Specific fixes with code examples]

### Handoff
When fixes approved, hand off to `implementer` agent.

Bad: Bloated and Unfocused (2,400 tokens)

---
description: "Security expert and code generator and tester"
tools: ['codebase', 'editor', 'filesystem', 'fetch', 'terminal']
---

# Security Expert Agent

## Background and Expertise
You are a world-class security engineer with 20 years of experience in cybersecurity, penetration testing, secure software development, cryptography, network security, cloud security, DevSecOps practices, threat modeling, incident response, and compliance frameworks including PCI-DSS, HIPAA, SOC 2, ISO 27001...

[... 500 tokens of background ...]

## OWASP Top 10 Detailed Explanations
### 1. Broken Access Control
Broken access control occurs when users can act outside of their intended permissions. This can happen when...

[... 1,200 tokens of detailed explanations ...]

## Security Testing Procedures
### Unit Testing Security
[... 300 tokens ...]

### Integration Testing Security  
[... 300 tokens ...]

[Multiple overlapping concerns, unclear focus]

Problems with bloated agent:

  • ❌ Mixed responsibilities (review + generate + test)
  • ❌ Excessive background information
  • ❌ Detailed explanations better suited for instruction files
  • ❌ Too many tools (should be focused)
  • ❌ No clear handoff strategy

Refactoring Oversized Agents

Pattern 1: Extract Common Knowledge to Instructions

Before: Agent includes language-specific rules (1,800 tokens)

# security-reviewer.agent.md (1,800 tokens)
---
description: "Security code reviewer"
---

## Python Security Rules
- Never use pickle on untrusted data
- Always use parameterized queries
- Validate user inputs with regex
[... 400 tokens of Python rules ...]

## JavaScript Security Rules  
[... 400 tokens of JavaScript rules ...]

## Java Security Rules
[... 400 tokens of Java rules ...]

After: Agent focuses on process, instructions handle language rules

# security-reviewer.agent.md (1,000 tokens)
---
description: "Security code reviewer"
---

## Your Role
Review code for security vulnerabilities following language-specific guidelines.

## Process
1. Identify language from file extension
2. Apply relevant security standards (auto-applied via instructions)
3. Report findings with severity levels
# .github/instructions/python-security.instructions.md
---
applyTo: "**/*.py"
---

# Python Security Guidelines
- Never use pickle on untrusted data
- Always use parameterized queries
[... Python-specific rules ...]

Pattern 2: Split by Responsibility

Before: Multi-purpose agent (2,200 tokens)

# dev-workflow.agent.md (2,200 tokens)
description: "Plan, implement, test, and review code"
tools: ['all']
---

I can plan features, write code, create tests, and review PRs...
[Tries to do everything]

After: Specialized agents with handoffs (3 files, 700-900 tokens each)

# planner.agent.md (800 tokens)
tools: ['codebase', 'search']
handoffs: [{ agent: implementer }]

# implementer.agent.md (900 tokens)
tools: ['editor', 'filesystem', 'codebase']
handoffs: [{ agent: test-specialist }]

# test-specialist.agent.md (700 tokens)  
tools: ['editor', 'terminal', 'codebase']
handoffs: [{ agent: code-reviewer }]

Pattern 3: Extract Examples to Context Files

Before: Agent with embedded examples (1,900 tokens)

## Output Format Examples

### Example 1: API Vulnerability Report
[... 300 tokens ...]

### Example 2: SQL Injection Report
[... 300 tokens ...]

### Example 3: XSS Vulnerability Report
[... 300 tokens ...]

After: Reference external examples (1,100 tokens)

## Output Format
Follow the report template in `.copilot/context/security-report-template.md`.

For examples, see `.copilot/context/examples/security-reports/`.

Length Validation Checklist

Before committing an agent file:

Measuring Agent File Length

# Quick token estimate (word count × 1.33)
wc -w .github/agents/security-reviewer.agent.md

# More accurate with Python
python -c "
import tiktoken
enc = tiktoken.get_encoding('cl100k_base')
with open('.github/agents/security-reviewer.agent.md') as f:
    print(len(enc.encode(f.read())), 'tokens')
"

Performance Impact

Agent Size Switch Time Context Impact Best For
< 500 tokens Instant Minimal Simple specialists
500-1,000 tokens < 1 second Low Standard agents
1,000-1,500 tokens 1-2 seconds Moderate Complex roles
1,500-2,000 tokens 2-3 seconds High Orchestrators only
> 2,000 tokens 3+ seconds ⚠️ Very High 🔴 Refactor required

By keeping agents focused and concise, you ensure smooth agent switching, preserve context window space for actual work, and maintain clarity of purpose throughout AI interactions.

🎯 Conclusion

Custom agents, prompts, and instructions form a powerful, composable system for customizing GitHub Copilot. By understanding each file type’s purpose and how they interact, you can create sophisticated AI workflows that provide:

  • Specialized personas through agents that define persistent roles and behaviors
  • Task-specific workflows through prompts that invoke targeted operations
  • Context-aware guidelines through instructions that apply automatically
  • Orchestrated processes through handoffs that transition between agents

Key Principles:

  1. Separation of Concerns: Prompts define tasks, agents define personas, instructions define rules
  2. Composability: Prompts reference agents, agents reference instructions, creating flexible combinations
  3. Tool Priority: Prompts > Agents > Defaults, enabling precise control
  4. Reusability: One agent serves multiple prompts; one instruction applies everywhere
  5. Handoffs: Agents coordinate multi-step workflows with user review points

By following the decision framework and composition patterns in this article, you can build a library of reusable, maintainable AI customizations that enhance your team’s productivity.

⚠️ Common Mistakes

Agent files introduce additional complexity compared to simple prompts, leading to unique pitfalls. These mistakes can cause agent failures, confusing handoff loops, or degraded performance.

Mistake 1: Persona Confusion - Multiple Roles in One Agent

Problem: Trying to make a single agent handle multiple distinct responsibilities dilutes its effectiveness.

❌ Bad example:

---
description: "Development assistant for coding, testing, deployment, and documentation"
tools: [fetch, search, terminal, file]
---

# Universal Developer Agent

I can help with:
- Writing code and implementing features
- Creating unit and integration tests
- Deploying to cloud platforms
- Writing technical documentation
- Reviewing code for security
- Optimizing performance
- Managing dependencies
[... tries to do everything ...]

Problems:

  • Too broad to excel at any single task
  • Context gets diluted across multiple domains
  • Hard to optimize tool selection
  • Unclear when to hand off to other agents

✅ Solution: Single-responsibility agents with clear handoffs:

# feature-developer.agent.md
---
description: "Implement new features with clean, tested code"
tools: [search, file]
handoffs:
  - label: "Generate Tests"
    agent: test-specialist
    prompt: "Create comprehensive tests for this implementation"
  - label: "Review Security"
    agent: security-auditor
    prompt: "Audit this code for security vulnerabilities"
---

# Feature Developer

I implement new features following these principles:

1. **Clean code** - Readable, maintainable, well-structured
2. **Documentation** - Clear comments and docstrings
3. **Error handling** - Graceful failures, meaningful errors

When implementation is complete, I can hand off to:
- `@test-specialist` for comprehensive testing
- `@security-auditor` for security review

Mistake 2: Handoff Loops Without Exit Conditions

Problem: Creating circular handoffs that cause infinite delegation.

❌ Bad example:

# agent-a.agent.md
handoffs:
  - label: "Send to B"
    agent: agent-b

# agent-b.agent.md
handoffs:
  - label: "Send back to A"
    agent: agent-a

Result: User gets stuck in A → B → A → B loop with no way forward.

✅ Solution: Clear workflow progression with terminal states:

# planner.agent.md
---
handoffs:
  - label: "Start Implementation"
    agent: feature-developer
    prompt: "Implement the plan above"
    send: false  # User reviews plan first
---

# feature-developer.agent.md
---
handoffs:
  - label: "Generate Tests"
    agent: test-specialist
    prompt: "Create tests for this implementation"
  # No handoff back to planner - workflow progresses forward
---

# test-specialist.agent.md
---
handoffs:
  - label: "Final Review"
    agent: code-reviewer
    prompt: "Review implementation and tests for merge readiness"
---

# code-reviewer.agent.md
---
# Terminal agent - provides final assessment, no further handoffs
---

Workflow: Planner → Developer → Tester → Reviewer → Done

Mistake 3: Over-Restricting Tools

Problem: Limiting tools too aggressively prevents agents from doing their job.

❌ Bad example:

---
description: "Research and implement features using external documentation"
tools: []  # No tools allowed
---

Research the best approach using official documentation, then implement.

Problem: Agent can’t actually fetch documentation or search the codebase.

✅ Solution: Provide necessary tools for the agent’s role:

---
description: "Research and implement features using external documentation"
tools: [fetch, search, file]  # All necessary tools
---

# Research & Implementation Agent

## Process

1. **Research** - Use `#fetch` to retrieve official documentation
2. **Context** - Use `@workspace` to understand existing patterns
3. **Implement** - Create or modify files following discovered best practices

Mistake 4: Vague Agent Descriptions

Problem: Description doesn’t clearly communicate agent’s purpose or capabilities.

❌ Bad examples:

description: "Helpful coding assistant"        # Too generic
description: "Agent for stuff"                 # Meaningless
description: "Does things with code and tests" # Vague

✅ Solution: Specific, action-oriented descriptions:

description: "Generate comprehensive test suites with edge case coverage"
description: "Refactor code to improve performance while maintaining behavior"
description: "Create React components following team design system standards"

Good description characteristics:

  • Action verb (Generate, Refactor, Create, Review)
  • Specific output (test suites, React components)
  • Quality criteria (comprehensive, following standards)
  • Constraint (while maintaining behavior)

Mistake 5: Missing or Incorrect send Field

Problem: Not understanding when to use send: true vs. send: false in handoffs.

❌ Bad example (automatic send when user should review):

---
handoffs:
  - label: "Deploy to Production"
    agent: deployment-agent
    prompt: "Deploy the changes above"
    send: true  # DANGER: Deploys without user confirmation
---

❌ Bad example (manual send when automatic makes sense):

---
handoffs:
  - label: "Format Code"
    agent: formatter
    prompt: "Apply code formatting"
    send: false  # Unnecessary manual step for safe operation
---

✅ Solution: Use send based on risk and user involvement:

# High-risk operation - user must review and confirm
handoffs:
  - label: "Deploy to Production"
    agent: deployment-agent
    prompt: "Deploy after user reviews and approves"
    send: false  # User clicks to confirm

# Safe operation - automatic progression
handoffs:
  - label: "Format Code"
    agent: formatter
    prompt: "Apply team code formatting standards"
    send: true   # Automatic, reversible, safe

# Planning step - user should review before implementation
handoffs:
  - label: "Start Implementation"
    agent: developer
    prompt: "Implement the plan outlined above"
    send: false  # User reviews plan first

Decision guide:

  • send: false → User reviews output before next step (planning, destructive operations, production changes)
  • send: true → Safe automation (formatting, linting, documentation generation)

Mistake 6: Agent File Length Bloat

Problem: Including extensive examples, documentation, or edge cases directly in agent file.

❌ Bad example:

---
description: "Create React components"
---

# React Component Generator

## Full Component Template

[... 200 lines of template code ...]

## Edge Cases

[... 150 lines of edge case handling ...]

## Styling Options

[... 100 lines of CSS approaches ...]

## Testing Patterns

[... 150 lines of test examples ...]

Total: 600+ lines, consuming context on every agent invocation.

✅ Solution: Keep agent concise, reference external documentation:

---
description: "Create React components following team design system"
tools: [fetch, file]
---

# React Component Generator

Create functional React components with TypeScript following:

## Structure
1. **Component file** - `ComponentName.tsx`
2. **Styles** - `ComponentName.module.css`
3. **Tests** - `ComponentName.test.tsx`
4. **Story** - `ComponentName.stories.tsx` (if applicable)

## Standards
Follow patterns in `.github/instructions/react-patterns.instructions.md`

## Design System
Reference components: #fetch:https://team.design-system.com/components

## Example
See `.copilot/context/examples/react-component-example.tsx`

Generate all files maintaining consistency with existing components.

Benefits:

  • Agent file: ~150 lines (vs. 600+)
  • Standards centralized and reusable
  • Examples available but not loaded unless needed

Mistake 7: Ignoring Target Context (v1.107+)

Problem: Not specifying target when creating agents for GitHub cloud execution vs. local VS Code.

❌ Bad example (cloud agent without target specification):

---
description: "PR review agent"
tools: [fetch, search, terminal]  # Terminal won't work in cloud
---

✅ Solution: Specify target and appropriate tools:

# Local agent (runs in VS Code)
---
description: "Local development assistant"
target: vscode
tools: [fetch, search, terminal, file]
---

# Cloud agent (runs in GitHub PRs)
---
description: "PR review agent for GitHub Actions"
target: github-copilot
tools: [fetch, search]  # No terminal in cloud
mcp-servers:
  - name: github-mcp
    url: https://github-mcp-server.azure.com
---

Target types:

  • vscode - Local execution (default), full tool access
  • github-copilot - Cloud execution, limited tools, MCP server support

Mistake 8: No Fallback for Missing Dependencies

Problem: Agent assumes tools, files, or services are always available.

❌ Bad example:

---
description: "Generate API documentation from OpenAPI spec"
---

Fetch the OpenAPI spec from `#file:openapi.yaml` and generate docs.

Problem: Fails if openapi.yaml doesn’t exist or is in a different location.

✅ Solution: Graceful degradation with fallbacks:

---
description: "Generate API documentation from OpenAPI spec"
tools: [search, fetch, file]
---

# API Documentation Generator

## Step 1: Locate OpenAPI Spec

Search for OpenAPI specification:
1. Check standard locations: `openapi.yaml`, `swagger.yaml`, `api-spec.yaml`
2. Search `docs/` and `api/` directories
3. Look for `openapi` in filename

**If not found:** Ask user for spec location or URL.

## Step 2: Generate Documentation

[Generate based on located spec]

## Step 3: Output Format

[Documentation structure]

If spec is unavailable, generate template documentation structure.

Key Takeaways

✅ DO:

  • Create single-responsibility agents with clear personas
  • Design linear workflow progressions (avoid circular handoffs)
  • Provide necessary tools for agent’s role
  • Write specific, action-oriented descriptions
  • Use send: false for high-risk or review-required handoffs
  • Keep agent files concise (reference external docs)
  • Specify target for cloud agents
  • Include fallback behavior for missing dependencies

❌ DON’T:

  • Make agents handle multiple unrelated responsibilities
  • Create circular handoff loops
  • Over-restrict tools needed for agent’s job
  • Write vague descriptions like “helpful assistant”
  • Auto-send dangerous operations (send: true for production deploys)
  • Bloat agent files with extensive examples and docs
  • Ignore execution context (local vs. cloud)
  • Assume dependencies always exist

By avoiding these agent-specific mistakes, you’ll build reliable, maintainable multi-agent workflows that enhance your team’s productivity without creating confusion or safety risks.

📚 References

Official GitHub Copilot Documentation

  • Custom Agents in VS Code [📘 Official]
    Comprehensive guide to creating custom agents with .agent.md files. Covers agent file structure, YAML frontmatter options, handoffs for workflow orchestration, tool configuration, and how agents differ from chat modes. Essential reading for understanding agent personas and multi-step workflows.

  • Use Prompt Files in VS Code [📘 Official]
    Documentation on creating reusable prompt files with .prompt.md extension. Explains how prompts reference agents via the agent field, tool priority order, variable substitution, and the relationship between prompts and agents. Critical for understanding how prompts and agents compose.

  • Use Custom Instructions in VS Code [📘 Official]
    Guide to creating instruction files with .instructions.md extension. Covers the applyTo frontmatter field for automatic application based on file patterns, how to reference instructions from prompts and agents, and best practices for context-specific rules. Important for understanding how instructions provide universal guidelines.

  • Use Tools in Chat [📘 Official]
    Comprehensive reference for GitHub Copilot tools including built-in tools, MCP tools, and tool sets. Explains tool approval process, how to reference tools with #tool: syntax, and tool configuration in agents and prompts. Essential for understanding agent capabilities and tool priority.

VS Code Release Notes

  • VS Code v1.107 Release Notes [📘 Official]
    December 2024 release introducing Agent HQ unified interface, background agents with work tree isolation, Claude skills support, MCP 1.0 features (Tasks, Sampling, Elicitation), and enhanced Language Models Editor with BYOK support. Essential reading for understanding unified agent architecture and execution contexts.

  • VS Code Background Agents Documentation [📘 Official]
    Official guide for using background agents with Git worktrees for isolation. Explains workflow for background agent creation, worktree management, and change application.

  • VS Code Agents Tutorial [📘 Official]
    Official tutorial for agent workflows covering local, background, and cloud agents. Demonstrates unified agent experience and delegation patterns.

Community Resources

  • Awesome GitHub Copilot - Custom Agents Examples [📒 Community]
    Community-curated collection of custom agents, prompts, and instructions. Browse real-world examples of agent personas, handoff workflows, and composition patterns. Valuable for learning from practical implementations.

📎 Appendix: Unified Agent Architecture (v1.107+)

VS Code 1.107 introduced a paradigm shift in how agents execute, providing a unified interface for managing agent sessions across multiple execution contexts.

Agent HQ Interface

Agent HQ is the centralized interface for managing all agent sessions:

Feature Functionality
Recent Sessions List Displays local, background, and cloud sessions with unified status
Read/Unread Markers Blue dots indicate unread completed sessions
Filtering & Search Filter by session type, search across session history
Archive Capability Move completed sessions to archive for cleaner workspace
Expand to Sidebar Full sidebar view for detailed session management

Execution Context Details

Local Agents

  • Execute in the current VS Code session
  • Interactive—user can observe and intervene in real-time
  • No isolation—changes affect workspace directly
  • Best for: Quick tasks, iterative refinement, learning agent behavior

Background Agents

  • Execute autonomously without blocking VS Code
  • Use Git work trees for complete filesystem isolation
  • Sessions continue even when VS Code loses focus
  • Changes reviewed and merged after completion
  • Best for: Long-running tasks, parallel work on multiple features

Work Tree Workflow:

  1. Create background agent session (dropdown option to use work tree)
  2. Agent works in isolated work tree—no conflicts with local changes
  3. Work tree appears in Source Control view
  4. Review changes after completion
  5. Use “Apply” action to integrate changes into main workspace

Cloud Agents

  • Execute on GitHub infrastructure
  • Automatically create branch and pull request
  • Fully asynchronous—can close VS Code entirely
  • Best for: Large changes, team collaboration, code review workflows

Delegation Flow

The unified architecture enables seamless delegation between execution contexts:

Planning Mode → Local Agent → Background Agent → Cloud Agent
      ↓              ↓              ↓               ↓
   Creates      Implements     Isolates via      Creates
    Plan         Locally      Work Trees     Branch + PR

“Continue In” options available from:

  • Chat view “Continue in” button
  • Planning mode delegation dropdown
  • Untitled prompt file button

Claude Skills Support

VS Code 1.107 added Claude Skills support, enabling agents to leverage the growing Claude skills ecosystem for extended capabilities. This allows custom agents to access specialized tools and behaviors defined in Claude skill files.

Impact on Agent Design

When designing custom agents, consider the execution context:

Agent Type Recommended Context Rationale
Planning agents Local Interactive refinement of plans
Implementation agents Background or Cloud Long-running, benefits from isolation
Review agents Local Interactive feedback needed
Documentation agents Background Can run while developer works

Best Practices:

  • Use target: github-copilot for agents intended for cloud execution
  • Design agents to work autonomously for background execution
  • Include clear success criteria so background/cloud agents know when complete
  • Consider using handoffs to transition from planning (local) to implementation (background/cloud)